<html>
	<head>
		<title>Preferences</title>
		<link rel="STYLESHEET" href="book.css" charset="ISO-8859-1" type="text/css"/>
	</head>
	<body>
		<h2>Preferences</h2>
		
		<p>
			The <b>P4Eclipse</b> plugin has a number of configuration options that 
			can influency its working. The various options can be found in the 
			<b>Eclipse</b> preferences dialog, found in 
			<span class="menu">Window->Preferences</span>.
		</p>
		
		<h3>
			<a name="GeneralPreferences">General preferences</a>
		</h3>
			
			<p>
				The <b>P4Eclipse</b> plugin has three preference pages, located in the
				preferences dialog, under the <span class="menu">Team</span> entry.
				The first page contains the general preferences for the plugin, and is shown
				when <span class="menu">Perforce</span> is selected.
			</p>
			<p>
				The following preferences can be set on the general preferences screen:
			</p>
			<center>
				<img src="../img/preferences-general.png" alt="General preferences screenshot"/>
			</center>
			<div>
				<table class="preferencesTable">
					<tr>
						<th>name</th>
						<th>description</th>
					</tr>
					<tr>
						<td class="preference">
							Deleting resources will remove them in the repository (p4 delete)
						</td>
						<td class="preference">
							When selected, removing a file under perforce control from the 
							workspace will also perform a perforce delete to remove the file 
							in the repository.
						</td>
					</tr>
					<tr>
					<td class="preference">Show added markers</td>
						<td class="preference">When selected, files newly added to the repository will be 
								marked with a '+'.</td>
					</tr>
					<tr>
					<td class="preference">Show full depot path for projects</td>
						<td class="preference">When selected, projects under perforce control will be marked with
								the full depot path for the repository root of the project</td>
					</tr>
					<tr>
					<td class="preference">Automatically open files on edit</td>
						<td class="preference">When selected, any file under perforce control that is changed
								will be automatically opened for edit. If not selected, files need
								to be explicitly opened for edit before they can be changed.</td>
					</tr>
					<tr>
					<td class="preference">Warn when opening files that are also opened by others</td>
						<td class="preference">When selected, a warning will be shown if a file is opened for edit 
								that is already opened for another client</td>
					</tr>
				</table>
			</div>
			<div>
				<h4>Submit options</h4>
					<center>
						<img src="../img/preferences-submit.png" alt="Submit options screenshot"/>
					</center>
						
					<table class="preferencesTable">
						<tr>
							<th>name</th>
							<th>description</th>
						</tr>
						<tr>
						<td class="preference">Prompt to add 'new' files before changelist submission</td>
							<td class="preference">When selected, the plugin will warn of any new files in the 
								project that have not been added to source control, and allow you
								to add them.</td>
						</tr>
						<tr>
						<td class="preference">Warn when submitting changelist that has warnings/errors</td>
							<td class="preference">When selected, the plugin will display a warning when 
								submitting files that have errors or warnings.</td>
						</tr>
						<tr>
						<td class="preference">When submitting unchanged resources...</td>
							<td class="preference">Select whether the plugin should automatically save resources
									before sumitting them, submit the unchanged version, or
									ask the user which of those two to do</td>
						</tr>
				</table>
			</div>

		<h3>
			<a name="BackgroundUpdates">Background Updates</a>
		</h3>
			<p>
				The second page contains the preferences for background updates
				for the plugin, and is shown when 
				<span class="menu">Perforce->Background&nbsp;Updates</span> 
				is selected.
			</p>
			<p>
				The <b>P4Eclipse</b> plugin can check the state of your files against the
				depot at regular intervals so the information on your project is kept up-to-date.
				This page provides the general settings for these background updates. Each
				project can be seperately in- or excluded from the updates by toggling the
				appropriate setting in its context properties dialog.
			</p>
			<center>
				<img src="../img/preferences-updates.png" alt="Background updates preferences screenshot"/>
			</center>			
			<p>
				The following preferences can be set on the Background Updates screen:
			</p>
			<div>
				<table class="preferencesTable">
					<tr>
						<th>name</th>
						<th>description</th>
					</tr>					
					<tr>
					<td class="preference">Interval for background upates (in seconds)</td>
						<td class="preference">The interval between the updates</td>
					</tr>
					<tr>
					<td class="preference">Monitor changelists for resource changes</td>
						<td class="preference">When seleced, the file in your changelists will be checked
								against the depot for new versions</td>
					</tr>
					<tr>
					<td class="preference">Monitor locally opened files for resource changes</td>
						<td class="preference">When selected, files that are locally opened, but not
								opened for edit in the depot, will be checked against the depot</td>
					</tr>
				</table>
			</div>
			
			<h3>
				<a name="LabelDecorations">Label Decorations</a>
			</h3>
			<p>
				The third preferences page is used to specify how the p4eclipse plugin presents itself 
				to the user. Every aspect of the label decorations that p4eclipse controls can be 
				configured here.				
			</p>
			<p>
				<b>Note: </b>These preferences will only take effect after Perforce label decorations 
				have been enabled in the <span class="menu">Workbench->Label&nbsp;Decorations</span>
				preference screen.
			</p>
			<h4>Text Settings</h4>
			<p>
				The following settings can be performed to influence the text labels p4eclipse can add to
				projects, folders and files. Every setting can be altered by editting the text field, and by adding
				relevant variables using the <span class="menu">Add variables...</span> button.
				Each setting is illustrated by an example.
			</p>
			<center>
				<img src="../img/preferences-label-text.png" alt="Text label decorations preferences screenshot"/>
			</center>			
				<table class="preferencesTable">
					<tr>
						<th>name</th>
						<th>default value</th>
						<th>description</th>
					</tr>
					<tr>
						<td class="preference">Project Format</td>
						<td class="preference">{dirty_flag}{name}[{p4port}]</td>
						<td class="preference">
							This label will appear as the project entry for any project under perforce control. It 
							can mark the project as having altered files ( <b>{dirty_flag}</b> ), and provide information 
							on the perforce related properties of the project, such as the username ( <b>{p4user}</b> ),
							the client view ( <b>{p4client}</b> ) and the perforce server and port ( <b>{p4port}</b> ).
						</td>
					</tr>
					<tr>
						<td class="preference">Folder Format</td>
						<td class="preference">{dirty_flag}{name}</td>
						<td class="preference">
							This label will appear as the folder entry within projects. It 
							can mark a folder as having altered files ( <b>{dirty_flag}</b> ), and provide information 
							on the perforce related properties of the project, such as the username ( <b>{p4user}</b> ),
							the client view ( <b>{p4client}</b> ) and the perforce server and port ( <b>{p4port}</b> ).
						</td>
					</tr>
					<tr>
						<td class="preference">File Format</td>
						<td class="preference">{dirty_flag}{name} {have_rev}</td>
						<td class="preference">
							This label will appear for each file under perforce control. It 
							can mark a file as being changed ( <b>{dirty_flag}</b> ), and provide information 
							on which revision you have of the file ( <b>{have_rev}</b> ) and which revision is the latest 
							in the depot ( <b>{head_rev}</b> ).
						</td>
					</tr>
					<tr>
						<td class="preference">Label decoration for outgoing</td>
						<td class="preference">&gt;</td>
						<td class="preference">
							This is the definition of the <b>{dirty_flag}</b> variable used in the preceding settings. It is
							used to mark items as changed since synchronizing with the depot.
						</td>
					</tr>
					<tr>
						<td class="preference">Label decoration for added</td>
						<td class="preference">*</td>
						<td class="preference">
							This decoration is used to mark items as newly added to the depot. It is not possible to
							disable use of this decorator, so there is no need to add it to any of the settings above.
						</td>
					</tr>					
				</table>
			<h4>Icon settings</h4>			
			<p>
				The icon settings enable or disable the various graphical hints that p4eclipse can add to the icon
				of a resource that is under perforce control. The graphical representation used is similar to the one
				in the official <i>Perforce</i> graphical clients, so they will probably be familiar.
			</p>
			<center>
				<img src="../img/preferences-label-icons.png" alt="Icons label decorations preferences screenshot"/>
			</center>			
			
			<h4>Other settings</h4>
			<p>
				The Label Decorations panel has one more setting, to enable 'Compute deep outgoing state for 
				folders'. When this setting is enabled, p4eclipse will recursively go down the resource tree to determine
				for all entries whether they have been changed since the last synchronization with the depot.  This is 
				disabled	by default, since it slows down the performance of the label decoration strongly.
			</p>
	</body>
</html>